home *** CD-ROM | disk | FTP | other *** search
/ Just Call Me Internet / Just Call Me Internet.iso / prog / atari / gfa / stik_gfa / stik_doc.txt next >
Encoding:
Text File  |  1997-06-08  |  10.9 KB  |  215 lines
  1. GFA-Basic Documentation for STiK  v1.08
  2. by Lonny Pursell
  3. (C)1997 by Lonny Pursell and ENCOM
  4. All rights reserved.
  5. Date: 6/8/1997
  6. E-Mail: atari@bright.net
  7.  
  8. ===========================================================================
  9. The purpose of this document is to show how to access STiK from GFA-Basic.
  10. It does not explain internet protocols and how they work.  Protocols such
  11. as POP3, HTTP, TELNET, and FTP are not covered and anyone wanting to
  12. implement such protocols should find the proper RFC or document.  Again
  13. this document only details the use of GFA-Basic to access the main STiK
  14. functions.
  15.  
  16. The GFA-Basic version of the STiK devkit was designed to follow the 'C'
  17. devkit as closely as possible.  Do to the differences in the two languages
  18. some things are a bit different.  For the most part the 'C' documention
  19. is very accurate and may help shed some light on some of the STiK calls.
  20. I suggest you at least look over the 'C' version of the devkit if you are
  21. curious about STiK or if you get confused and need further information.
  22.  
  23. If a parameter is not explained it should be left as is.  The variable
  24. types used are very important so don't change them!  None of the KRxx
  25. functions are detailed as they should be avoided.  The UDP_xx functions
  26. should not be used unless you know what you are doing.  Functions not
  27. listed here are ones I don't use or considered not that important.  If you
  28. understand the ones listed the others should be easy enough to figure out
  29. on your own.  It's worth noting that I used GFA-Basic 3.6TTe to make the
  30. STiK library so if lesser versions complain about the syntax that is
  31. probably the cause.
  32.  
  33. ---------------------------------------------------------------------------
  34. FUNCTION: init_stik()
  35.  PURPOSE: must be called once to allow STiK access from GFA-Basic
  36.   SYNTAX: result&=@init_stik
  37.   OUTPUT: result& - if 0 then STiK is loaded and can be accessed
  38.                     if other than 0 then an error occured
  39.                        0 - STiK access is granted
  40.                       -1 - SYSTEM HAS NO COOKIE JAR
  41.                       -2 - STiK NOT FOUND
  42.                       -3 - STiK IS DISABLED
  43.                       -4 - STiK MAGIC NOT FOUND
  44.                       -5 - TRANSPORT LAYER NOT LOADED
  45.     NOTE: not an actual STiK call but interfaces STiK with GFA-Basic
  46. ---------------------------------------------------------------------------
  47. FUNCTION: resolve()
  48.  PURPOSE: converts a domain name into an IP address
  49.   SYNTAX: result&=@resolve(domain$,0,V:ip%,1)
  50.    INPUT: domain$ - the site you want to convert into an IP address
  51.             V:ip% - address of where we want to store the IP address
  52.   OUTPUT: result& - if positive no error occured
  53.                     if negative an error occured
  54.               ip% - will contain the IP address when the function returns
  55.     NOTE: if the IP address is known then resolve() in not really needed
  56. ---------------------------------------------------------------------------
  57. FUNCTION: tcp_open()
  58.  PURPOSE: opens a connection
  59.   SYNTAX: result&=@tcp_open(ip%,port%,0,bufsize&)
  60.    INPUT:      ip% - IP address of site to connect to
  61.              port% - port number (depends on protocol used)
  62.           bufsize& - amount of ram STiK should allocate for the connection
  63.   OUTPUT:  result& - if positive it's the handle assigned to the connection
  64.                      if negative an error occured
  65.     NOTE: result&=@tcp_open(0,0,0,bufsize&) !this would be a listen socket
  66.             buffer size depends on the protocol you are using
  67.             the ram is allocated from STiK's internal ram
  68.             STiK's internal ram size is set with the ALLOCMEM= tag
  69. ---------------------------------------------------------------------------
  70. FUNCTION: tcp_send()
  71.  PURPOSE: send data across a connection
  72.   SYNTAX: result&=@tcp_send(cn&,buf%,len&)
  73.    INPUT:     cn& - connection handle returned from tcp_open()
  74.              buf% - address of memory buffer containing data to be sent
  75.              len& - how many bytes should be sent
  76.   OUTPUT: result& - if positive no error occured
  77.                     if negative an error occured
  78. ---------------------------------------------------------------------------
  79. FUNCTION: tcp_close()
  80.  PURPOSE: close an open connection
  81.   SYNTAX: result&=@tcp_close(cn&,timeout&)
  82.    INPUT:      cn& - connection handle returned from tcp_open()
  83.           timeout& - timeout value in seconds
  84.   OUTPUT:  result& - if positive no error occured
  85.                      if negative an error occured
  86.     NOTE: the ram allocated for a connection is freed when it's closed
  87. ---------------------------------------------------------------------------
  88. FUNCTION: tcp_wait_state()
  89.  PURPOSE: waits for a connection to reach a state within a time limit
  90.   SYNTAX: result&=@tcp_wait_state(cn&,state&,timeout&)
  91.    INPUT:      cn& - connection handle returned from tcp_open()
  92.             state& - connection state you want to wait for
  93.                      refer to the connection state list below
  94.           timeout& - timeout value in seconds
  95.   OUTPUT:  result& - if positive no error occured
  96.                      if negative an error occured
  97.     NOTE: should probably not be used on listen sockets
  98. ---------------------------------------------------------------------------
  99. FUNCTION: cnbyte_count()
  100.  PURPOSE: returns the number of bytes that came in on a given connection
  101.   SYNTAX: count&=@cnbyte_count(cn&)
  102.    INPUT:    cn& - connection handle returned from tcp_open()
  103.   OUTPUT: count& - if positive it's the number bytes that came in
  104.                    if negative an error occured
  105.     NOTE: a return value of 0 simply means no data waiting
  106. ---------------------------------------------------------------------------
  107. FUNCTION: cnget_char()
  108.  PURPOSE: fetches a single byte from a given connection
  109.   SYNTAX: char&=@cnget_char(cn&)
  110.    INPUT:   cn& - connection handle returned from tcp_open()
  111.   OUTPUT: char& - if positive it's a byte that came in
  112.                   if negative an error occured
  113.     NOTE: depending on your application this might be too slow
  114. ---------------------------------------------------------------------------
  115. FUNCTION: cnget_block()
  116.  PURPOSE: fetches a block of bytes from a given connection
  117.   SYNTAX: result&=@cnget_block(cn&,buf%,len&)
  118.    INPUT:     cn& - connection handle returned from tcp_open()
  119.              buf% - memory address to put incoming data in
  120.              len& - number of bytes to fetch from the connection
  121.   OUTPUT: result& - if positive it should be the same as len& going in
  122.                     if negative an error occured
  123.     NOTE: much faster than cnget_char() but harder to use
  124. ---------------------------------------------------------------------------
  125. FUNCTION: cngetinfo()
  126.  PURPOSE: returns information about a given connection
  127.   SYNTAX: pointer%=@cngetinfo(cn&)
  128.    INPUT:      cn& - connection handle returned from tcp_open()
  129.   OUTPUT: pointer% - address of structure containing connection information
  130.                      refer to table below for a list
  131.     NOTE: as of STiK version 1.13 there is a revised structure
  132. ---------------------------------------------------------------------------
  133. FUNCTION: carrier_detect()
  134.  PURPOSE: determines the state of the modems carrier detect signal
  135.   SYNTAX: result&=@carrier_detect
  136.   OUTPUT: result& - returns  0 if the config tag CDVALID=FALSE (unknown)
  137.                     returns  1 for carrier detected
  138.                     returns -1 for no carrier detected
  139.     NOTE: STiK does a carrier detect internally (error code -19)
  140. ---------------------------------------------------------------------------
  141. FUNCTION: getvstr$()
  142.  PURPOSE: fetches tag settings from the STiK configuration files
  143.   SYNTAX: result$=@getvstr$(tag$)
  144.    INPUT:    tag$ - the tag you are wanting the setting of
  145.   OUTPUT: result$ - the setting of the tag you specified
  146.                     returns the tag setting if it's found and =something
  147.                     returns an empty string if the tag is not set or found
  148.     NOTE: you should probably not invent your own tags
  149. ---------------------------------------------------------------------------
  150. FUNCTION: get_err_text$()
  151.  PURPOSE: returns an error code as a string of text
  152.   SYNTAX: result$=@get_err_text$(code&)
  153.    INPUT:   code& - the error code you'd like as a string of text
  154.                     refer to the error code table below for a list
  155.   OUTPUT: result$ - error code& converted to a string of text
  156. ---------------------------------------------------------------------------
  157. FUNCTION: version$()
  158.  PURPOSE: returns the STiK version number
  159.   SYNTAX: result$=@version$
  160.   OUTPUT: result$ - returns the version of STiK as a string of text
  161.     NOTE: format of string will be "00.00"
  162.  
  163. ===========================================================================
  164. Connection States:
  165.    0 - No connection.  Null, void, absent, ...
  166.    1 - Wait for remote request
  167.    2 - Connect request sent.  Await matching request
  168.    3 - Wait for connection ACK  (Listener only ??)
  169.    4 - Connection is established.  Handshake completed
  170.    5 - Await termination request or acknowledgement
  171.    6 - Await termination request
  172.    7 - Await termination request from local user
  173.    8 - Await termination acknowledge from remote TCP
  174.    9 - Await acknowledgement of terminate request sent
  175.   10 - Delay to ensure remote has received term' ACK
  176. ===========================================================================
  177. cngetinfo structure:
  178.   uword - protocol   TCP or UDP or ... 0 means CIB is not in use
  179.   uword - lport      TCP client port      (ie: local machine)
  180.   uword - rport      TCP server port      (ie: remote machine)
  181.   ulong - rhost      TCP server IP addr   (ie: remote machine)
  182.   ulong - client_ip  IP address of client (STiK version 1.13 or higher)
  183. ===========================================================================
  184. Error Codes:
  185.     0 - No error occured ...
  186.    -1 - Output buffer is full (not fatal)
  187.    -2 - No data available     (not falal)
  188.    -3 - EOF from remote
  189.    -4 - RST received from remote
  190.    -5 - RST.  Other end sent unacceptable pkt
  191.    -6 - Something failed due to lack of memory
  192.    -7 - Connection refused by remote
  193.    -8 - A SYN was received in the window
  194.    -9 - Bad connection handle used
  195.   -10 - The connection is in LISTEN state
  196.   -11 - No free CCB's available
  197.   -12 - No connection matches this packet (TCP)
  198.   -13 - Failure to connect to remote port (TCP)
  199.   -14 - Invalid TCP_close() requested
  200.   -15 - A user function timed out
  201.   -16 - A the connection timed out
  202.   -17 - Can't resolve the hostname
  203.   -18 - Domain name or dotted dec. bad format
  204.   -19 - The modem disconnected
  205.   -20 - Hostname does not exist
  206.   -21 - Resolver Work limit reached
  207.   -22 - No nameservers could be found for query
  208.   -23 - Bad format of DS query
  209.   -24 - Destination unreachable
  210.   -25 - No address records exist for host
  211.   -26 - Routine is unavailable
  212.    26 - ABS of last error code in this list
  213. ===========================================================================
  214. eof
  215.